Skip to content

feat(cli): search sees your integrations, and build stops calling one word a match - #5320

Open
josephfarina wants to merge 3 commits into
mainfrom
cli-search-integrations-build-coverage
Open

feat(cli): search sees your integrations, and build stops calling one word a match#5320
josephfarina wants to merge 3 commits into
mainfrom
cli-search-integrations-build-coverage

Conversation

@josephfarina

Copy link
Copy Markdown
Contributor

Three changes to the two commands an agent reaches for first.

search could not see integrations

search gathered components straight off the resolved core directory, so a package listed in astryx.config.mjs was reachable by component and template and invisible to the one command whose job is finding things. The search command already loaded a Project — purely to print integration warnings beside results that could not contain an integration's components.

It now gathers through Project, so an integration's components rank next to Core's and carry their own package and import. The per-integration skip+warn policy is inherited, so one broken manifest is skipped rather than failing the command, and Project is loaded once per search and shared with the docs gatherer.

Usage guidance was not indexed

Component candidates carried name + keywords + usage.description. The reader's vocabulary usually lives further down: Banner describes itself as "a persistent message", and only its guidance names the form errors and maintenance notices someone would search for.

features and best-practice text are now indexed, at a tier below the description. The tiers stay apart deliberately — collapsed into one, Toast ("a brief, non-blocking notification") ties with every component that mentions notifications in passing advice, and ties break alphabetically.

MIN_TOKEN_SCORE moves with the new tier, since it gates which per-token hits count in the multi-word pass and build sends multi-word queries almost exclusively.

build called a one-word coincidence a direct match

astryx --json build "actionable warning banner"
→ directMatch: true
→ pages: contact-form 95, documentation-design 95, login 95

None of those is a warning page. A page's keywords include every component its source renders, so each keyword-matched "banner" at 90; the multi-word branch adds a coverage garnish of up to 15 points, landing exactly on the 95 direct-match threshold. Coverage was decorating the score when it should have been gating it — matching one of three concepts is not the claim that matching three is.

Results now carry matchedTerms / queryTerms (a whole-phrase match reports full coverage), and the pages group gates on them. Consumers no longer have to parse "matches 1/3 terms: banner" back out of the reason string.

A thin kit says what to try

Left unsaid, an empty kit reads as "the package has nothing for this" rather than "these words missed", and the caller falls back on whatever it already believed about the package — which is the failure build exists to prevent. build.kit now carries an optional hint when the kit is nearly empty, naming the browse commands; the renderer prints it.

Testing

  • Full suite green: 544 files, 11280 tests. lint:strict clean on every touched file; check:cli-structure, typecheck:authoring, typecheck:strict, readme:check all pass; API declarations regenerated with sync:api-types.
  • New tests cover each behaviour, including a temp-directory fixture integration (manifest + doc + same-stem source) proving an integration-owned component is found with its package and import path, and that Core results still come back beside it.
  • directMatch positive control: build "contact form" still reports a direct match at 2/2 coverage.

The type additions are additive.

@vercel

vercel Bot commented Aug 22, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Sep 2, 2026 10:35pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Aug 22, 2026
@github-actions

github-actions Bot commented Aug 22, 2026

Copy link
Copy Markdown
Contributor

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

No new or modified components detected.

Bundle Size Summary

No component packages changed.

Accessibility Audit

Status: No accessibility violations detected.


Generated by PR Enrichment workflow | Storybook | Sandbox | View full report

github-actions Bot added a commit that referenced this pull request Aug 22, 2026
@josephfarina
josephfarina marked this pull request as ready for review September 1, 2026 21:23
@josephfarina
josephfarina requested a review from ernestt September 1, 2026 21:24

@cixzhang cixzhang left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks — two headline fixes landed while this was open: #5259 added integration search and #5614 fixed false direct matches at the scorer, so this head now conflicts in both search files.

The remaining rewrite regresses two established paths. A builder following an integration result gets @astryxdesign/core, while component correctly reports @acme/widgets/DiffLink. An invalid or duplicate config also turns the parent’s 20-result Core button search into an empty success (exit 0), telling the agent Astryx has nothing.

Please rebase onto current main and reuse the component lookup/fallback path. Could the guidance indexing and thin-kit hint return as separate small PRs, each with true red→green evidence and updated public response docs?

[Reviewed by Robohands]

…in kit

Rebased onto main, which landed integration search (#5259) and the
scorer-level false-direct-match fix (#5614) while this was open. Both are
main's implementations and are untouched: this branch no longer rewrites
gatherComponents, so the two regressions that rewrite caused go with it — an
integration result reports its own package again, and a broken config no
longer turns a Core `button` search into an empty success.

What is left is the part that did not land. A page template's keywords include
every component its source renders, so `build "actionable warning banner"`
returned login, contact-form and documentation-design at 95 apiece on an exact
hit for "banner" alone. Coverage now gates the pages group instead of
garnishing the score, and a thin kit names the browse commands rather than
reading as "the package has nothing".

scoreQuery reports the coverage it already computed as matchedTerms /
queryTerms, because a single strong hit and a broad weak one land on the same
score and the gate cannot tell them apart otherwise.

The guidance-tier indexing goes up separately, as asked.
Review asked for the guidance indexing and the thin-kit hint as separate small
PRs. The hint is now #5938 and the guidance tier is #5937, so this branch keeps
only the coverage gate on the build pages group and the matchedTerms/queryTerms
plumbing that gate needs.

No behaviour change to the gate itself.
…h too

The split removed `hint` from the kit and its type but left build.mjs
destructuring it, so Typecheck CLI (strict) failed with TS2339 and took
build-storybook and build down with it. The renderer change belongs to #5938
with the rest of the hint.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants